<!DOCTYPE html>

<html lang="en" data-content_root="./">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Usage &#8212; TIMSCONVERT 2.0.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
    <link rel="stylesheet" type="text/css" href="_static/basic.css?v=c058f7c8" />
    <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=27fed22d" />
    <script src="_static/documentation_options.js?v=51b770b3"></script>
    <script src="_static/doctools.js?v=9a2dae69"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Advanced Usage" href="advanced.html" />
    <link rel="prev" title="Installation" href="installation.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  

  
  

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <section id="usage">
<h1>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h1>
<section id="gui-usage">
<h2>GUI Usage<a class="headerlink" href="#gui-usage" title="Link to this heading">¶</a></h2>
<p>The TIMSCONVERT GUI can be started by downloading directly from the Github release or installing <code class="docutils literal notranslate"><span class="pre">timsconvert</span></code> via
pip. If downloaded from Github, unzip the folder and open <code class="docutils literal notranslate"><span class="pre">TIMSCONVERT.exe</span></code>. If installed via pip to a virtual
environment, run the <code class="docutils literal notranslate"><span class="pre">timsconvert_gui</span></code> command to start the GUI. The following window should appear.</p>
<img alt="TIMSCONVERT GUI Main Window" src="_images/timsconvert_gui_usage_01.png" />
<p>Once open, two columns will appear in the GUI. One the left is the data conversion queue. Click on the
<code class="docutils literal notranslate"><span class="pre">Add</span> <span class="pre">Bruker</span> <span class="pre">timsTOF</span> <span class="pre">Data</span> <span class="pre">to</span> <span class="pre">Queue</span></code> button to open a file dialogue window and select either a Bruker <code class="docutils literal notranslate"><span class="pre">*.d</span></code> directory
or a directory containing multiple <code class="docutils literal notranslate"><span class="pre">*.d</span></code> directories. All <code class="docutils literal notranslate"><span class="pre">*.d</span></code> directories that are found will appear in the
<code class="docutils literal notranslate"><span class="pre">Queue</span></code>.</p>
<img alt="Multiple *.d directories added to the sample queue." src="_images/timsconvert_gui_usage_02.png" />
<p>If unwanted directories have been added, one or more rows in the <code class="docutils literal notranslate"><span class="pre">Queue</span></code> can be selected and removed by
highlighting them and clicking on the <code class="docutils literal notranslate"><span class="pre">Remove</span> <span class="pre">from</span> <span class="pre">Queue</span></code> button.</p>
<img alt="Selecting one or more *.d directories from the sample queue to be removed." src="_images/timsconvert_gui_usage_03.png" />
<p>On the right, all data conversion parameters can be found. See below for more infomation on each parameter. Once the
conversion parameters have been configured, click on the <code class="docutils literal notranslate"><span class="pre">Convert</span> <span class="pre">Data</span></code> button to begin data conversion. Adding or
removing data will be unavailable until the current conversion has completed, and each row will be replaced with a
progress bar.</p>
<img alt="Data conversion progress shown in the queue for each dataset." src="_images/timsconvert_gui_usage_04.png" />
<p>Please note that for larger datasets, you may see a message that says TIMSCONVERT is Not Responding. This is due to
the program using more computation power to convert data; the GUI will remain unresponsive but the data conversion will
still process in the background, and control will be returned when the process has finished.</p>
<p>Once completely, a message will appear to show that the current job has finished, in addition to any errors that may
have occurred during the data conversion process.</p>
<img alt="TIMSCONVERT data conversion completed message box." src="_images/timsconvert_gui_usage_05.png" />
</section>
<section id="command-line-usage">
<h2>Command Line Usage<a class="headerlink" href="#command-line-usage" title="Link to this heading">¶</a></h2>
<p>The command line interface version of TIMSCONVERT supports conversion of all experimental types specified above.</p>
<section id="basic-example">
<h3>Basic Example<a class="headerlink" href="#basic-example" title="Link to this heading">¶</a></h3>
<p>Only the <code class="docutils literal notranslate"><span class="pre">input</span></code> parameter is required to run TIMSCONVERT. By default, the output file(s) can be found in the same
directory as the input data using the same filenames as the original .d file(s). Please note that any previously
converted mzML/imzML files in the output directory with the same filename will be overwritten. If no other parameters
are specified, their default values will be used.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">timsconvert</span> <span class="o">--</span><span class="nb">input</span> <span class="p">[</span><span class="n">path</span> <span class="n">to</span> <span class="n">data</span><span class="p">]</span>
</pre></div>
</div>
<p>Depending on the size of your data and the number of files being converted, TIMSCONVERT may take some time to finish
conversion.</p>
<p>For a full list of parameters, use the <code class="docutils literal notranslate"><span class="pre">--help</span></code> flag.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">timsconvert</span> <span class="o">--</span><span class="n">help</span>
</pre></div>
</div>
<p>See below for a full list of descriptions for each parameter.</p>
</section>
</section>
<section id="parameters">
<h2>Parameters<a class="headerlink" href="#parameters" title="Link to this heading">¶</a></h2>
<table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>Parameter</p></td>
<td><p>Description</p></td>
</tr>
<tr class="row-even"><td><p>input</p></td>
<td><p>Filepath for one or more Bruker <a href="#id1"><span class="problematic" id="id2">*</span></a>.d directories containing TSF or TDF file or directory containing multiple Bruker <a href="#id3"><span class="problematic" id="id4">*</span></a>.d directories.</p></td>
</tr>
<tr class="row-odd"><td><p>outdir</p></td>
<td><p>Path to folder in which to write output file(s). Defaults to the input directory path.</p></td>
</tr>
<tr class="row-even"><td><p>mode</p></td>
<td><p>Choose whether export to spectra in “raw”, “centroid”, or “profile” formats. Defaults to “centroid”.</p></td>
</tr>
<tr class="row-odd"><td><p>compression</p></td>
<td><p>Choose between ZLIB compression (“zlib”) or no compression (“none”). Defaults to “zlib”.</p></td>
</tr>
<tr class="row-even"><td><p>ms2_only</p></td>
<td><p>Boolean flag that specifies only MS2 spectra should be converted.</p></td>
</tr>
<tr class="row-odd"><td><p>use_raw_calibration</p></td>
<td><p>TIMSCONVERT uses the recalibrated data when available. Use this flag to prevent use of recalibrated data and instead use the raw uncalibrated data.</p></td>
</tr>
<tr class="row-even"><td><p>pressure_compensation_strategy</p></td>
<td><p>Whether to parse data as is (“none”), apply global TIMS funnel pressure compensation (“global”), or apply per frame TIMS funnel pressure compensation (“frame”). Defaults to “global”.</p></td>
</tr>
<tr class="row-odd"><td><p>exclude_mobility</p></td>
<td><p>Boolean flag used to exclude trapped ion mobility spectrometry data from exported data. Precursor ion mobility information is still exported.</p></td>
</tr>
<tr class="row-even"><td><p>mz_encoding</p></td>
<td><p>Choose encoding for mz array: 32-bit (“32”) or 64-bit (“64”). Defaults to 64-bit.</p></td>
</tr>
<tr class="row-odd"><td><p>intensity_encoding</p></td>
<td><p>Choose encoding for intensity array: 32-bit (“32”) or 64-bit (“64”). Defaults to 64-bit.</p></td>
</tr>
<tr class="row-even"><td><p>mobility_encoding</p></td>
<td><p>Choose encoding for mobility array: 32-bit (“32”) or 64-bit (“64”). Defaults to 64-bit.</p></td>
</tr>
<tr class="row-odd"><td><p>profile_bins</p></td>
<td><p>Number of bins used to bin data when converting in profile mode. A value of 0 indicates no binning is performed. Defaults to 0.</p></td>
</tr>
<tr class="row-even"><td><p>barebones_metadata</p></td>
<td><p>Only use basic mzML metadata. Use if downstream data analysis tools throw errors with descriptive CV terms.</p></td>
</tr>
<tr class="row-odd"><td><p>maldi_output_file</p></td>
<td><p>For MALDI dried droplet data, whether individual scans should be placed in individual files (“individual”), combined into a single file (“combined”), or combined by sample label (“sample”). Defaults to “combined”.</p></td>
</tr>
<tr class="row-even"><td><p>maldi_plate_map</p></td>
<td><p>Plate map to be used for parsing spots if –maldi_output_file == “individual” or –maldi_output_file == “sample”. Should be a .csv file with no header/index.</p></td>
</tr>
<tr class="row-odd"><td><p>imzml_mode</p></td>
<td><p>Whether .imzML files should be written in “processed” or “continuous” mode. Defaults to “processed”.</p></td>
</tr>
<tr class="row-even"><td><p>verbose</p></td>
<td><p>Boolean flag to determine whether to print logging output.</p></td>
</tr>
</tbody>
</table>
<section id="notes-on-mode-parameter">
<h3>Notes on <code class="docutils literal notranslate"><span class="pre">mode</span></code> Parameter<a class="headerlink" href="#notes-on-mode-parameter" title="Link to this heading">¶</a></h3>
<p>There are 3 options for exporting spectra: <code class="docutils literal notranslate"><span class="pre">raw</span></code>, <code class="docutils literal notranslate"><span class="pre">centroid</span></code>, and <code class="docutils literal notranslate"><span class="pre">profile</span></code> mode. This section describes what
each mode means for different types of raw data.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">TSF</span></code> and <code class="docutils literal notranslate"><span class="pre">BAF</span></code> files, <code class="docutils literal notranslate"><span class="pre">raw</span></code> and <code class="docutils literal notranslate"><span class="pre">centroid</span></code> modes are equivalent and will export data in centroid mode.
Note that for <code class="docutils literal notranslate"><span class="pre">raw</span></code> mode, all spectra will be labeled as centroided. For these file types, <code class="docutils literal notranslate"><span class="pre">profile</span></code> mode is also
as described and will export spectra in profile mode.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">TDF</span></code> files in which the data is exported without writing out the ion mobility binary arrays, <code class="docutils literal notranslate"><span class="pre">raw</span></code> mode
exports centroided spectra using the <code class="docutils literal notranslate"><span class="pre">tims_read_scans_v2</span></code> function from Bruker’s <code class="docutils literal notranslate"><span class="pre">TDF-SDK</span></code>. Note that as mentioned
above, all spectra will be labeled as centroided. <code class="docutils literal notranslate"><span class="pre">centroid</span></code> mode exports centroided spectra using a different
function, <code class="docutils literal notranslate"><span class="pre">tims_extract_centroided_spectrum_for_frame_v2</span></code> function from <code class="docutils literal notranslate"><span class="pre">TDF-SDK</span></code>. This results in minor
differences in the resulting line spectra, but most major peaks should be equivalent. For <code class="docutils literal notranslate"><span class="pre">profile</span></code> mode <code class="docutils literal notranslate"><span class="pre">TDF</span></code>
files, the <code class="docutils literal notranslate"><span class="pre">tims_extract_profile_for_frame</span></code> function is used to extract a quasi-profile spectrum from the raw data.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">TDF</span></code> files in which the data is exported with the ion mobiilty arrays (resulting in 3 binary data arrays for
m/z, intensity, and ion mobility, only <code class="docutils literal notranslate"><span class="pre">raw</span></code> mode is available due to conversion speed and the resulting data size if
<code class="docutils literal notranslate"><span class="pre">centroid</span></code> or <code class="docutils literal notranslate"><span class="pre">profile</span></code> mode are used. Again, all spectra are labeled as centroided.</p>
</section>
<section id="notes-on-pressure-compensation-strategy-parameter">
<h3>Notes on <code class="docutils literal notranslate"><span class="pre">pressure_compensation_strategy</span></code> Parameter<a class="headerlink" href="#notes-on-pressure-compensation-strategy-parameter" title="Link to this heading">¶</a></h3>
<p>The pressure compensation strategy parameter is used on data import via Bruker’s <code class="docutils literal notranslate"><span class="pre">TDF-SDK</span></code>. This parameter determines
whether a calculation is applied to normalize the mobility (1/K0) dimension between datasets in which the pressure of
the TIMS cell is modified between acquisitions. <code class="docutils literal notranslate"><span class="pre">none</span></code> prevents the application of any pressure compensation.
<code class="docutils literal notranslate"><span class="pre">global</span></code> applies the pressure compensation across the entire dataset in a given <code class="docutils literal notranslate"><span class="pre">*.d</span></code> file. <code class="docutils literal notranslate"><span class="pre">frame</span></code> applies the
pressure compensation on a per frame basis.</p>
</section>
<section id="notes-on-barebones-metadata-parameter">
<h3>Notes on <code class="docutils literal notranslate"><span class="pre">barebones_metadata</span></code> Parameter<a class="headerlink" href="#notes-on-barebones-metadata-parameter" title="Link to this heading">¶</a></h3>
<p>If the <code class="docutils literal notranslate"><span class="pre">--barebones_metadata</span></code> flag is used when running TIMSCONVERT, the following metadata is not written to the
resulting mzML file: 1) software list including acquistion and data conversion software, 2) data processing list
including data conversion software, and 3) instrument name. This is done to allow for compatibility with older software
predating the timsTOF, TDF-SDK, psims, etc. that cannot recognize those <code class="docutils literal notranslate"><span class="pre">CVParams</span></code>. Additionally, TIMSCONVERT is
written out as a <code class="docutils literal notranslate"><span class="pre">UserParam</span></code>, and although it is technically correct, the presence of that <code class="docutils literal notranslate"><span class="pre">UserParam</span></code> is not
always compatible with these software.</p>
</section>
</section>
<section id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Link to this heading">¶</a></h2>
<p>To test TIMSCONVERT locally:</p>
<ul>
<li><p>Download test data.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="p">[</span><span class="n">path</span> <span class="n">to</span> <span class="n">timsconvert</span><span class="p">]</span><span class="o">/</span><span class="n">test</span>
<span class="n">make</span> <span class="n">download_test</span>
</pre></div>
</div>
</li>
<li><p>Test Python CLI workflow</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="p">[</span><span class="n">path</span> <span class="n">to</span> <span class="n">timsconvert</span><span class="p">]</span><span class="o">/</span><span class="n">test</span>
<span class="n">make</span> <span class="n">run_test</span>
<span class="n">make</span> <span class="n">run_test_mobility</span>
</pre></div>
</div>
</li>
<li><p>Test Nextflow workflow</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="p">[</span><span class="n">path</span> <span class="n">to</span> <span class="n">timsconvert</span><span class="p">]</span><span class="o">/</span><span class="n">test</span>
<span class="n">make</span> <span class="n">run_nextflow_mobility</span>
</pre></div>
</div>
</li>
</ul>
</section>
</section>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">TIMSCONVERT</a></h1>









<search id="searchbox" style="display: none" role="search">
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Local Usage</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#gui-usage">GUI Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="#command-line-usage">Command Line Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="#parameters">Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="#testing">Testing</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="advanced.html">Advanced Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="timsconvert.html">TIMSCONVERT Source Code</a></li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Modules</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="installation.html" title="previous chapter">Installation</a></li>
      <li>Next: <a href="advanced.html" title="next chapter">Advanced Usage</a></li>
  </ul></li>
</ul>
</div>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &#169;2021-2024, Gordon T. Luu.
      
      |
      Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.0.2</a>
      &amp; <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
      
      |
      <a href="_sources/local.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>